=============
Configuration
=============

SYNTAX
======

:file:`sieverc` consists of statements and comments, each of which
must occur on a line of its own. Comments start with a "#", which
may be preceded by whitespace. Empty lines are ignored, but may
not contain other whitespace.


STATEMENTS
==========

.. confvar:: account [login@]host

    Subsequent statements only apply to accounts matching `login` and `host`.
    If `login` is omitted, all accounts on `host` match.

.. confvar:: authmechs mechanism, ...

    Comma-separated list of authentication mechanisms, ordered by preference.

    Either a combination of password-based mechanisms:

    * ``scram-sha3-512-plus``
    * ``scram-sha-512-plus``
    * ``scram-sha-384-plus``
    * ``scram-sha-256-plus``
    * ``scram-sha-224-plus``
    * ``scram-sha-1-plus``
    * ``scram-sha3-512``
    * ``scram-sha-512``
    * ``scram-sha-384``
    * ``scram-sha-256``
    * ``scram-sha-224``
    * ``scram-sha-1``
    * ``plain``
    * ``cram-md5`` (obsolete)
    * ``login`` (obsolete)

    Or:

    * ``external``

    Shell-like patterns are expanded to non-obsolete
    mechanisms in the above order.

    Default: ``scram-*, plain``

.. confvar:: alias string

    Use `string` as alias for the current host.

.. confvar:: backup policy

    Emacs-like backup policy.
    One of:

    ``none``
        Do not make backups (default).

    ``simple``
        Back up :file:`file` to :file:`file~`.

    ``numbered``
        Back up :file:`file` to :file:`file.~{n}~`, where
        *n* starts with 1 and increments with each backup.

    See the GNU Emacs manual (chap. `19.3.2 <emacs-backup_>`_) for details.

.. confvar:: cafile file

    Load custom certificate authorities (CAs) from `file`,
    `file` must be in PEM format.

.. confvar:: cadir dir

    Load custom certificate authorities (CAs) from `dir`, which must
    contain one PEM file per CA, each of which must be named after the
    hash of its subject name.

    .. only:: man

        See :man:`c_rehash(1)` for details.

    .. only:: html

        See SSL_CTX_load_verify_locations_ for details.

.. confvar:: cert file

    Read the client TLS certificate from `file`. `file` must be in PEM
    format and contain the certificate and every CA certificate required to
    establish the certificate's authenticity. The TLS key is also read
    from `file` unless :confvar:`key` is set, too.

.. confvar:: confdir dir

    Configuration directory.
    Defaults to the directory :file:`sieverc` was found in or, if
    :file:`sieverc` does not exist, :file:`{$XDG_CONFIG_HOME}/sieve`.

.. confvar:: confirm command, ...

    Comma-separated list of commands that require confirmation
    if they overwrite or remove a file.

    Either a combination of:

    * :sievecmd:`cp`
    * :sievecmd:`get` (also applies to :sievecmd:`mget`)
    * :sievecmd:`mv`
    * :sievecmd:`put` (also applies to :sievecmd:`mput`)
    * :sievecmd:`rm`

    Or one of:

    * ``all`` (default)
    * ``none``

.. confvar:: debugauth level

    Include authentication in debugging output?
    One of:

    ``no``
        Do *not* include the authentication exchange (default).

    ``sasl``
        Print the SASL messages sent/received.

    ``sieve``
        Print the ManageSieve messages sent/received.

    .. danger::
        Debugging output printed with :confvar:`debugauth` set to
        ``sieve`` or ``sasl`` contains your password.

.. confvar:: getkeypass command

    Read the TLS key passphrase from the standard output of :samp:`{command}`.

.. confvar:: getpass command

    Read the login password from the standard output of :samp:`{command}`.

.. confvar:: host hostname|address

    Host to connect to (default: :file:`localhost`).

.. confvar:: key file

    Read the client TLS key from `file`. `file` must be in PEM format.

.. confvar:: login username

    Login as *username*.

.. confvar:: port port

    Connect to `port` (default: 4190).

.. confvar:: tls boolean

    Secure connections with Transport Layer Security (TLS)?
    ``yes`` (default) or ``no``.

    .. danger::
        Data sent over an unsecured connection can be
        intercepted, read, and modified by third parties.

.. confvar:: saslprep credentials

    Which `credentials` to normalise. One of:

    * ``usernames``
    * ``passwords``
    * ``all`` (default)
    * ``none``

    Adjust if valid credentials are rejected.

.. confvar:: stacktrace boolean

    Show stack traces even for expected errors?
    ``yes`` or ``no`` (default).

.. confvar:: verbosity level

    One of:

    * ``error``
    * ``warning``
    * ``info`` (default)
    * ``debug``

    The higher the level, the fewer messages are printed,
    where ``error`` is highest and ``debug`` lowest.

.. confvar:: x509strict boolean

    Be strict when checking TLS certificates?
    ``yes`` (default) or ``no``.


VARIABLES
=========

:samp:`~`, :samp:`~{user}`, :code:`$var`, and :code:`$\{var\}` are
expanded in commands and filenames.

:samp:`~` and :samp:`~{user}` are expanded to the home directory of the
current and the given `user` respectively, but only if they occur at
the start of a word.

:code:`$var` and :code:`$\{var\}` are expanded to the configuration
variable `var`. '\$' can be escaped by prefixing it with an additional
'\$' (e.g., :code:`$$var` is expanded to :code:`$var`).

Commands are split into words before '~' and variables are expanded.
Word-splitting is not performed on filenames.


FILES
=====

:file:`{$XDG_CONFIG_HOME}/sieve/sieverc`

:file:`{$HOME}/.sieve/sieverc`

:file:`{$HOME}/.sieverc`

:file:`/etc/sieve/sieverc`

:file:`/etc/sieverc`
    The configuration is read from the first of those files that exists.


EXAMPLES
========

Recommended configuration:

.. code:: none

    # Backup scripts before changing them
    backup simple

    # Only require confirmation for removing scripts
    confirm rm

    # Be less verbose
    verbosity warning

    # Accounts
    account imap.foo.example
        alias foo
        login user

    account imap.bar.example
        alias bar
        login user@bar.example

Lookup passwords stored by Apple Mail or MailMate_ in macOS' Keychain:

.. code:: none

    getpass security find-internet-password -s$host -a$login -w

Lookup passwords in `GNU Privacy Guard`_-encrypted files:

.. code:: none

    getpass gpg -d $confdir/$login@$host.gpg

Use TLS authentication to login as :samp:`user@bar.example`
on :file:`imap.bar.example`:

.. code:: none

    # Read passwords from encrypted files
    getpass gpg -d $confdir/$login@$host.gpg

    # Accounts
    account imap.foo.example
        alias foo
        login user

    account imap.bar.example
        alias bar
        authmechs external
        cert $confdir/client.crt
        key $confdir/client.key
        login user@bar.example


.. only:: man

    SEE ALSO
    ========

    :manpage:`sievemgr(1)`


.. _`GNU Privacy Guard`: https://gnupg.org

.. _MailMate: https://freron.com/

.. _SSL_CTX_load_verify_locations: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_load_verify_locations.html#DESCRIPTION

.. _emacs-backup: https://www.gnu.org/software/emacs/manual/html_node/emacs/Backup.html
